Inside Macintosh: QuickDraw GX Graphics /

Chapter 6 - Picture Shapes / Picture Shapes Reference

Functions / Creating Picture Shapes

GXNewPicture

You can use the GXNewPicture function to create a new picture shape.

gxShape GXNewPicture(long count, const gxShape shapes[], 
                     const gxStyle styles[], const gxInk inks[],
                     const gxTransform transforms[])

count

The number of picture items in the new picture shape.

shapes

An array of references to the shapes you want to include in the picture.

styles

An array of references to the style objects you want to use as overriding styles for the picture items. You may provide nil for this parameter if you do not want any overriding styles.

inks

An array of references to the ink objects you want to use as overriding inks for the picture items. You may provide nil for this parameter if you do not want any overriding inks.

transforms

An array of references to the transform objects you want to use as overriding transforms for the picture items. You may provide nil for this parameter if you do not want any overriding transforms.

function result

A reference to the newly created picture shape.

DESCRIPTION

The GXNewPicture function creates a new picture shape.

In the count parameter, you specify the number of shapes you want to include as items of the picture, and in the shapes parameter, you provide references to the shapes.

In the styles parameter, you specify references to overriding styles. Each item of this array overrides the style of the corresponding shape in the shapes array. For example, the first style you provide in the styles array becomes the overriding style for the first shape in the shapes array, and so on. Similarly, in the inks and transforms parameters you specify references to overriding inks and transforms.

You may specify 0 for the count parameter and nil for the shapes, styles, inks, and transforms parameters to create an empty picture--a picture containing no picture items. You may provide nil for the styles, inks, or transforms parameters even if you provide shape references in the shapes parameter. In this case, the newly created picture shape contains picture items, but those items contain no overriding styles, inks, or transforms.

You may also provide nil for an individual item of a styles, inks, or transforms array if you do not want the corresponding picture item to have an overriding style, ink, or transform.

SPECIAL CONSIDERATIONS

If no error results, the GXNewPicture function creates a picture shape; you are responsible for disposing of this shape when you no longer need it. See Inside Macintosh: QuickDraw GX Objects for information about creating and disposing of shapes.

ERRORS, WARNINGS, AND NOTICES

Errors

out_of_memory

parameter_is_nil

shape_is_nil

parameter_out_of_range

SEE ALSO

For information about picture items and their overriding styles, inks, and transforms, see "About Picture Shapes" beginning on page 6-3.

For an example using this function, see "Creating and Drawing Picture Shapes" beginning on page 6-27.

To draw a picture shape once you've created one, use the GXDrawShape function, described in the chapter "Shape Objects" of Inside Macintosh: QuickDraw GX Objects.

For information about disposing of picture shapes, see the description of the GXDisposeShape function, which is in the chapter "Shape Objects" of Inside Macintosh: QuickDraw GX Objects.

Main | Page One | What's New | Apple Computer, Inc. | Find It | Contact Us | Help